<html>
<head>
<title>GeoPackage vector</title>
</head>

<body bgcolor="#ffffff">

<h1>GeoPackage vector</h1>

<p>This driver implements support for access to spatial tables in the
<a href="http://www.opengeospatial.org/standards/geopackage">OGC GeoPackage format standard</a>
The GeoPackage standard uses a SQLite database file as a generic container, and the standard defines:
</p>
<ul>
  <li>Expected metadata tables (<code>gpkg_contents</code>, <code>gpkg_spatial_ref_sys</code>, <code>gpkg_geometry_columns</code>)</li>
  <li>Binary format encoding for geometries in spatial tables (basically a GPKG standard header object followed by ISO standard well-known binary (WKB))</li>
  <li>Naming and conventions for extensions (extended feature types) and indexes (how to use SQLite r-tree in an interoperable manner)</li>
</ul>
<p>This driver reads and writes SQLite files from the file system, so it must be run by a user with read/write access to the files it is working with.</p>
<p>Starting with GDAL 2.0, the driver also supports reading and writing the
following non-linear geometry types :CIRCULARSTRING, COMPOUNDCURVE, CURVEPOLYGON, MULTICURVE and MULTISURFACE</p>

<p>Starting with GDAL 2.0, GeoPackage raster/tiles are supported. See
<a href="drv_geopackage_raster.html">GeoPackage raster</a> documentation page</p>

<h2>Specification version</h2>

<p>Starting with GDAL 2.2, the driver is able to create GeoPackage databases
following the 1.0/1.0.1, 1.1 or 1.2 versions.
For GDAL 2.2, it will automatically
adjust to the minimum version required for the features of GeoPackage used.
For GDAL 2.3 or later, it will default to 1.2.
Explicit version choice can be done by specifying the VERSION dataset creation
option.</p>

<h2>Limitations</h2>

<ul>
<li>GeoPackage only supports one geometry column per table.</li>
</ul>

<h2>SQL</h2>

<p>The driver supports OGR attribute filters, and users are expected
  to provide filters in the SQLite dialect, as they will be executed directly
  against the database.
</p>
<p>
  Starting with GDAL 2.0, SQL SELECT statements passed to ExecuteSQL() are
  also executed directly against the database. If Spatialite is used, a recent
  version (4.2.0) is needed and use of explicit cast operators AsGPB() is required
  to transform GeoPackage geometries to Spatialite geometries (the reverse conversion
  from Spatialite geometries is automatically done by the GPKG driver).
  It is also possible to use with any Spatialite version, but in
  a slower way, by specifying the "INDIRECT_SQLITE" dialect. In which case,
  GeoPackage geometries automatically appear as Spatialite geometries after translation by OGR.
</p>

<p>Starting with GDAL 2.2, the "DROP TABLE layer_name" and "ALTER TABLE layer_name RENAME TO new_layer"
statements can be used. They will update GeoPackage system tables.</p>

<p>When dropping a table, or removing records from tables, the space they
occupied is not immediately released and kept in the pool of file pages that
SQLite may reuse later. If you need to shrink the file to its minimum size,
you need to issue an explicit "VACUUM" SQL request. Note that this will
result in a full rewrite of the file.</p>

<h3>SQL functions</h3>

Starting with GDAL 2.0, the following SQL functions, from the GeoPackage specification, are available :
<ul>
<li>ST_MinX(geom <i>Geometry</i>) : returns the minimum X coordinate of the geometry</li>
<li>ST_MinY(geom <i>Geometry</i>) : returns the minimum Y coordinate of the geometry</li>
<li>ST_MaxX(geom <i>Geometry</i>) : returns the maximum X coordinate of the geometry</li>
<li>ST_MaxY(geom <i>Geometry</i>) : returns the maximum Y coordinate of the geometry</li>
<li>ST_IsEmpty(geom <i>Geometry</i>) : returns 1 is the geometry is empty (but not null), e.g. a POINT EMPTY geometry</li>
<li>ST_GeometryType(geom <i>Geometry</i>) : returns the geometry type : 'POINT',
'LINESTRING', 'POLYGON', 'MULTIPOLYGON', 'MULTILINESTRING', 'MULTIPOINT', 'GEOMETRYCOLLECTION'</li>
<li>ST_SRID(geom <i>Geometry</i>) : returns the SRID of the geometry</li>
<li>GPKG_IsAssignable(expected_geom_type <i>String</i>, actual_geom_type <i>String</i>) : mainly, needed for the 'Geometry Type Triggers Extension'</li>
</ul>

The following functions, with identical syntax and semantics as in Spatialite, are also available :

<ul>
<li>CreateSpatialIndex(table_name <i>String</i>, geom_column_name <i>String</i>) : creates a spatial index (RTree) on the specified table/geometry column</li>
<li>DisableSpatialIndex(table_name <i>String</i>, geom_column_name <i>String</i>) : drop an existing spatial index (RTree) on the specified table/geometry column</li>
</ul>

<h3>Link with Spatialite</h3>

<p>
Starting with GDAL 2.0, if it has been compiled against Spatialite 4.2 or later,
it is also possible to use Spatialite SQL functions. Explicit transformation
from GPKG geometry binary encoding to Spatialite geometry binary encoding must be done.
</p>

<pre>
ogrinfo poly.gpkg -sql "SELECT ST_Buffer(CastAutomagic(geom),5) FROM poly"
</pre>

<p>
Starting with Spatialite 4.3, CastAutomagic is no longer needed.
</p>

<h2>Transaction support (GDAL &gt;= 2.0)</h2>

<p>
The driver implements transactions at the database level, per
<a href="http://trac.osgeo.org/gdal/wiki/rfc54_dataset_transactions">RFC 54</a>
</p>

<h2>Opening options</h2>

The following open options are available:
<ul>
<li><b>LIST_ALL_TABLES</b>=AUTO/YES/NO: (GDAL &gt;=2.2) Whether all tables, including
those non listed in gpkg_contents, should be listed. Defaults to AUTO.
If AUTO, all tables including those non linsted in gpkg_contents will be listed,
except if the aspatial extension is found or a table is registered as 'attributes'
in gpkg_contents. If YES, all tables including those non linsted in gpkg_contents will be listed,
in all cases. If NO, only tables registered as 'features', 'attributes' or 'aspatial'
will be listed.
</li>
</ul>

Note: open options are typically specified with "-oo name=value" syntax in
most OGR utilities, or with the GDALOpenEx() API call.

<h2>Creation Issues</h2>

<p>When creating a new GeoPackage file, the driver will attempt to
  force the database into a UTF-8 mode for text handling, satisfying
  the OGR strict UTF-8 capability. For pre-existing files, the driver
  will work with whatever it's given.</p>

<h3>Dataset Creation Options</h3>

<p>The following creation options (specific to vector, or common with raster)
are available:</p>

<ul>
<li><b>VERSION</b>=AUTO/1.0/1.1/1.2: (GDAL &gt;= 2.2) Set GeoPackage version
(for application_id and user_version fields). In AUTO mode, this will be equivalent
to 1.2 starting with GDAL 2.3.</li>
<li><b>ADD_GPKG_OGR_CONTENTS</b>=YES/NO: (GDAL &gt;= 2.2) Defines whether to add
a gpkg_ogr_contents table to keep feature count, and associated triggers.
Defaults to YES.</li>
</ul>

<p>Other options are available for raster. See the
<a href="drv_geopackage_raster.html">GeoPackage raster</a> documentation page</p>

<h3>Layer Creation Options</h3>

<ul>
<li><b>GEOMETRY_NAME</b>: Column to use for the geometry column. Default to "geom". Note: option was called GEOMETRY_COLUMN in releases before GDAL 2</li>
<li><b>GEOMETRY_NULLABLE</b>: (GDAL &gt;=2.0)  Whether the values of the geometry column can be NULL. Can be set to NO so that geometry is required. Default to "YES"</li>
<li><b>FID</b>: Column name to use for the OGR FID (primary key in the SQLite database). Default to "fid"</li>
<li><b>OVERWRITE</b>: If set to "YES" will delete any existing layers that have the same name as the layer being created. Default to NO</li>
<li><b>SPATIAL_INDEX</b>: (GDAL &gt;=2.0) If set to "YES" will create a spatial index for this layer. Default to YES</li>
<li><b>PRECISION</b>: (GDAL &gt;=2.0)  This may be "YES" to force new fields created on this
layer to try and represent the width of text fields (in terms of UTF-8 characters, not bytes), if available
using TEXT(width) types. If "NO" then the type TEXT will be used instead. The default is "YES".<p>
<li><b>TRUNCATE_FIELDS</b>: (GDAL &gt;=2.0)  This may be "YES" to force truncated of field values
that exceed the maximum allowed width of text fields, and also to "fix" the passed string if needed
to make it a valid UTF-8 string. If "NO" then the value is not truncated nor modified. The default is "NO".<p>
<li><b>IDENTIFIER</b>=string: (GDAL &gt;=2.0) Identifier of the layer, as put in the contents table.<p>
<li><b>DESCRIPTION</b>=string: (GDAL &gt;=2.0) Description of the layer, as put in the contents table.<p>
<li><b>ASPATIAL_VARIANT</b>=GPKG_ATTRIBUTES/OGR_ASPATIAL/NOT_REGISTERED: (GDAL &gt;=2.2) How to register non spatial tables.
Defaults to GPKG_ATTRIBUTES in GDAL 2.2 or later (behaviour in previous version
was equivalent to OGR_ASPATIAL).
Starting with GeoPackage 1.2, non spatial tables are part of the specification.
They are recorded with data_type="attributes"
in the gpkg_contents table. This is only compatible of GDAL 2.2 or later.
Priorly, in OGR 2.0 and 2.1, the "aspatial" extension had
been developed for similar purposes, so if selecting OGR_ASPATIAL, non spatial
tables will be recorded with data_type="aspatial" and the "aspatial" extension
was declared in the gpkg_extensions table. It is also possible to use the
NOT_REGISTERED option, in which case the non spatial table is not registered at
all in any GeoPackage system tables.<p>
</ul>

<h3>Metadata</h3>

<p>(GDAL &gt;=2.0) GDAL uses the standardized <a href="http://www.geopackage.org/spec/#_metadata_table">
<code>gpkg_metadata</code></a> and <a href="http://www.geopackage.org/spec/#_metadata_reference_table">
<code>gpkg_metadata_reference</code></a> tables to read and write metadata,
on the dataset and layer objects.</p>

<p>GDAL metadata, from the default metadata domain and possibly other metadata
domains, is serialized in a single XML document, conformant with the format used
in GDAL PAM (Persistent Auxiliary Metadata) .aux.xml files, and registered with
md_scope=dataset and md_standard_uri=http://gdal.org in gpkg_metadata.
For the dataset, this entry is referenced in gpkg_metadata_reference with a
reference_scope=geopackage.
For a layer, this entry is referenced in gpkg_metadata_reference with a
reference_scope=table and table_name={name of the table}</p>

<p>Metadata not originating from GDAL can be read by the driver and will be
exposed as metadata items with keys of the form GPKG_METADATA_ITEM_XXX and
values the content of the <i>metadata</i> columns of the gpkg_metadata table.
Update of such metadata is not currently supported through GDAL interfaces (
although it can be through direct SQL commands).</p>

<p>The specific DESCRIPTION and IDENTIFIER metadata item of the default metadata
domain can be used in read/write to read from/update the corresponding columns of
the gpkg_contents table.</p>

<h3>Non-spatial tables</h3>

<p>The core GeoPackage specification of GeoPackage 1.0 and 1.1 did not support
non-spatial tables. This was added in GeoPackage 1.2 as the "attributes"
data type.</p>

<p>Starting with GDAL 2.0, the driver allows creating and reading non-spatial
tables with the     <a href="geopackage_aspatial.html">Aspatial Support</a>
(<code>gdal_aspatial</code>) extension.</p>

<p>Starting with GDAL 2.2, the driver will also, by default, list non spatial tables
that are not registered through the gdal_aspatial extension, and support the
GeoPackage 1.2 "attributes" data type as well. Starting with GDAL 2.2, non
spatial tables are by default created following the GeoPackage 1.2 "attributes"
data type (can be controlled with the ASPATIAL_VARIANT layer creation option)</p>

<h3>Spatial views</h3>

<p>Views can be created and recognized as valid spatial layers if a corresponding
record is inserted into the gpkg_contents and gpkg_geometry_columns table.</p>

<p>Starting with GDAL 2.2, in the case of the columns in the SELECT clause of
the view acts a integer primary key, then it can be recognized by OGR as the
FID column of the view, provided it is renamed as OGC_FID. Selecting a feature
id from a source table without renaming will not be sufficient, since due to
joins this feature id could appear several times. Thus the user must explicitly
acknowledge that the column is really a primary key.</p>

<p>For example:</p>
<pre>
CREATE VIEW my_view AS SELECT foo.fid AS OGC_FID, foo.geom, ... FROM foo JOIN another_table ON foo.some_id = another_table.other_id
INSERT INTO gpkg_contents (table_name, identifier, data_type, srs_id) VALUES ( 'my_view', 'my_view', 'features', 4326)
INSERT INTO gpkg_geometry_columns (table_name, column_name, geometry_type_name, srs_id, z, m) values ('my_view', 'my_geom', 'GEOMETRY', 4326, 0, 0)
</pre>

<p>This requires GDAL to be compiled with the SQLITE_HAS_COLUMN_METADATA option
and SQLite3 with the SQLITE_ENABLE_COLUMN_METADATA option. Starting with GDAL 2.3,
this can be easily verified if the SQLITE_HAS_COLUMN_METADATA=YES driver metadata item
is declared (for example with "ogrinfo --format GPKG")</p>

<h3>Examples</h3>

<ul>
<li>
Simple translation of a single shapefile into GeoPackage.  The table 'abc' will
be created with the features from abc.shp and attributes from abc.dbf.
The file <code>filename.gpkg</code> must <strong>not</strong> already exist,
as it will be created. For adding new layers into existing geopackage run 
ogr2ogr with <strong>-update</strong>.
<pre>
% ogr2ogr -f GPKG filename.gpkg abc.shp
</pre>
</li>

<li>
Translation of a directory of shapefiles into a GeoPackage. Each file will end
up as a new table within the GPKG file.
The file <code>filename.gpkg</code> must <strong>not</strong> already exist, as it will be created.
<pre>
% ogr2ogr -f GPKG filename.gpkg ./path/to/dir
</pre>
</li>

<li>
Translation of a PostGIS database into a GeoPackage. Each table in the database will end up
as a table in the GPKG file.
The file <code>filename.gpkg</code> must <strong>not</strong> already exist, as it will be created.
<pre>
% ogr2ogr -f GPKG filename.gpkg PG:'dbname=mydatabase host=localhost'
</pre>
</li>

</ul>

<h3>See Also</h3>

<ul>
<li> <a href="http://sqlite.org/">SQLite</a><p>
<li> <a href="drv_geopackage_raster.html">GeoPackage raster</a> documentation page</li><p>
<li> <a href="http://www.geopackage.org/spec/">OGC GeoPackage format standard</a> specification, HTML format (current/development version of the standard)</li><p>
<li> <a href="http://www.opengeospatial.org/standards/geopackage">OGC GeoPackage Encoding Standard</a> page</li><p>
</ul>

</body>
</html>
